YAML configuration

To define a complete estimation problem, WOLF requires a YAML configuration file that specifies all the necessary components and parameters, including:

This YAML file(s) will be first validated and if no errors found, the WOLF problem will be configured.

See also

See Example of a WOLF ROS2 application to see an example of a YAML configuration file.

Modular YAML file: ‘follow’

Usually, a robotics team develops several projects over time. These projects have their own particular specificities, but share a large part of common material, both in therms of hardware and software.

Shared parts among different projects are typically,

  • Sensors hardware

  • Sensor calibration values

  • Data processing algorithms, tuned for a particular sensor

Non-shared parts can be diverse, but we’ll definitely find:

  • different sensor types and number

  • different sensor locations in the robot

  • different tuning of the processing algorithms, or variations with respect to the standard tuning

When it comes to specifying a new robotics project, it is not convenient to have to write a whole YAML file from scratch. We want to use as much of the re-usable material as possible avoiding copy-pasting blocks of parameters resulting in huge configuration files.

To accomplish that, the key follow can be used to include the content of another YAML file. For example, suppose that we create a new file odomicp_params.yaml containing the parameters of a ProcessorOdomIcp:

voting_active: false
voting_aux_active: false
time_tolerance: 0.1
min_features_for_keyframe: 5
max_new_features: 10
use_point_to_line_distance: 1
max_correspondence_dist: 1
max_iterations: 20
use_corr_tricks: 1
outliers_maxPerc: 0.9
outliers_adaptive_order: 0.7
outliers_adaptive_mult: 1.5
vfk_min_dist: 4.0
vfk_min_angle: 1.0
vfk_min_time: 5.0
vfk_min_error: 5.0
vfk_max_points: 130
...

Then, the processor specification in the main YAML file would be modified as follows

...
   -
      type:        "ProcessorOdomIcp"
      name:        "odometer_laser"
      sensor_name: "scanner_front_left"
      follow:      "/absolute/path/to/odomicp_params.yaml"
      # or
      follow:      "./relative/path/to/odomicp_params.yaml"
...

Note

If a string parameter starts with “.” it is understood as a relative path, and the path of the file will be tracked to guarantee its correctness. This is specially important in the case of using “follow” to a file in another folder.

YAML Validation

WOLF uses the yaml-schema-cpp library to specify and validate the structure and content of the YAML configuration files. This way, the expected user input is properly documented and validated in order to provide complete, comprehensive and exhaustive error messages in case of wrong user input. A dummy example of error messages printed is shown above:

---------------------------------------------------------------------------------
Log of applySchema to YAML file
yaml file: /path/to/the/input.yaml
schema: Example.schema
---------------------------------------------------------------------------------

ERROR in 'map1/param2': Wrong value. Allowed values defined in OPTIONS.
Schema specification:
DOC: some doc
MANDATORY: true
TYPE: string
OPTIONS:
- what
- the
- hell

ERROR in 'map1/param3': Wrong type.
Schema specification:
DOC: some doc
MANDATORY: true
TYPE: double

ERROR in 'param4': Missing mandatory field.
Schema specification:
DOC: some doc
MANDATORY: true
TYPE: string

YAML Templates

Using yaml-schema-cpp, we also provide yaml templates for all WOLF plugins and ROS2 packages. The YAML templates provided in the yaml_templates folder serve as a starting point for configuring your WOLF applications. You will find them in the folder yaml_templates of the corresponding repositories (plugin and ROS2 packages), and they include all the necessary keys with dummy values along with the doc messages, to define the components and parameters required for each specific use case.

For example, the following template is provided for a WOLF ROS2 subscriber that reads 2D odometry data from a ROS2 topic:

SubscriberOdom2d YAML Template
type: "whatever"  # DOC The class name - TYPE string
package: "whatever"  # DOC ROS package where the class is implemented - TYPE string
topic: "whatever"  # DOC Topic of the ROS publisher/subscriber - TYPE std::string
sensor_name: "whatever"  # DOC Name of the WOLF sensor corresponding to this subscriber - TYPE std::string
odom_from_pose: false  # DOC If the odometry has to be computed from the field "pose" of consecutive messages. If false, it will be computed multiplying "twist" by the time between consecutive messages. - TYPE bool

To use a template, you can copy its content to your main YAML file, or save it as a separate file and include it in your main YAML file using the follow key.